Monkey language reference

This manual describes the syntax and general concepts behind the core Monkey language.

About this reference
Programs and declarations
Strict mode
Comments
Identifiers
Types
Variables
Constants
Expressions
Statements
Functions
Methods
Classes
Generics
Interfaces
Exceptions
Modules
Public and private
External declarations
Memory management
Preprocessor

About this reference

A monospaced font is used for program code examples, for example:

Function Main()
Print "Hello World!"
End

Language syntax explanations are generally formatted as follows:

Anything that appears in bold indicates literal text. For example: Function means the actual text 'Function'.

Anything that appears in italics indicates other syntax. For example: Identifier means any text that is a valid identifier.

Anything that appears in square brackets [ ] is optional. For example: [ Step ] means the literal text Step is optional.

The pipe character | is use for alternatives. For example: To | Until means you can use To or Until - but not both.

A three dots ellipsis is used to indicate repetition.

These rules are not strictly followed. Where it makes sense to do so, syntax may be shown in a simplified form with explanatory notes.

Programs and declarations

A Monkey program consists of one or more modules, each of which is a separate file, consisting of a series of declarations.

A declaration associates a 'meaning' with an identifier. For example, this declaration...

Global x:Int

...indicates that the identifier 'x' is a global variable of type 'Int' (an integer).

Monkey supports the following kinds of declarations:

Modules
Constants
Local, Global and Field variables
Classes
Functions
Methods

A module is itself a kind of declaration and is represented by a single source file. The name of the module is taken from the name of the source file. For example, if your file is named "particles.monkey" then the module will be called "particles".

Modules may 'import' other modules, which may in turn import other modules and so on.

Every Monkey program has a 'main module' that must contain a public function called Main that takes no parameters and returns an integer. For example:

Function Main()
Print "That's all folks!"
End

This is the entry point of the program and is where program execution begins.

If you are using the mojo framework of modules, you must create a new class (which extends the base mojo.app class) and create a new instance of it in the Main function. See the mojo.app Module Reference for more information. An example of this is:

Import mojo.app
Import mojo.graphics

Class MyApp Extends App
    Method OnRender()
        DrawText "Hello World!",0,0
    End
End

Function Main()
        New MyApp
End

Strict mode

By default, Monkey allows you to take certain shortcuts when programming.

However, Monkey also offers a special Strict mode for programmers who prefer a stricter language definition.

The differences between strict and non-strict mode are:

In non-strict mode, variable type, function return type and function parameter types can be optionally omitted. In this case they will default to Int. In strict mode, you must always specify the type of all variables, functions return values and function parameters.

In non-strict mode, Return statements can be omitted at the end of a function. In this case, a Return statement will be automatically generated that will return an appropriate default value for the function type. That is, False for bool, 0 for int and float, "" for string, [] for arrays and Null for objects. In strict mode, a function that does not return Void must end with a Return statement.

In non-strict mode, the brackets around function call parameters are optional if the function is being used as a statement, or if the function can be called with no parameters. In strict mode, all function call parameters must be enclosed in brackets.

To use strict mode, a Strict directive must be placed at the very top of your module. For example:

Strict

Function Main:Int()                     'in Strict mode, the :Int type definition is compulsory
   Print( "Strict mode is...strict!" )  'in Strict mode, all function calls require brackets.
   Return 0                             'in strict mode, we MUST return a value.
End

The examples in this document will be presented in non-strict form.

Comments

You can add line comments to your programs using the ' (apostrophe) character. Everything following the ' character until the end of the line will be ignored.

You can add block comments to your programs using #rem and #end. These must appear at the start of a new line, although they may optionally have whitespace characters in front. Everything between #rem and #end will be ignored. Block comments can also be nested.

Here is an example of using comments:

Print "Hello World" 'This is a line comment!

#Rem 'start of a block comment
Print "The sound of silence!" 'inside a block comment
#End

Identifiers

Identifiers must start with an alphabetic character, or a single underscore followed by an alphabetic character. The rest of the identifier may contain any combination of alphanumeric characters and/or underscores.

Identifiers are case sensitive (except for language keywords - see below). For example, player, Player, PLAYER and PLayER are all different identifiers. This allows you to reuse the same name for different purposes. For example, Actor may refer to a class while actor refers to an object of that class.

Here are some examples of valid Monkey identifiers:

score
player1
player_up
_internal
helloworld
HelloWorld

Language keywords and reserved identifiers

The following identifiers are language keywords and are reserved for use by the Monkey language:

Void Strict Public Private Property Bool Int Float String Array
Object Mod Continue Exit Import Extern New Self Super Try Catch
Eachin True False Not Extends Abstract Final Select Case Default
Const Local Global Field Method Function Class And Or Shl Shr
End If Then Else ElseIf EndIf While Wend Repeat Until Forever
For To Step Next Return Module Interface Implements Inline Throw

Language keywords are case insensitive - for example, you may use the keyword function, Function or indeed even fUNCTION (not recommended) to declare a function.

The keywords Module, Inline and Array are not currently used by the Monkey language but are reserved for future use.

Monkey naming conventions

The standard Monkey modules use a simple naming convention:

All-caps case (eg: 'ALLCAPS' ): Constants.

Pascal case (eg: 'PascalCase' ): Globals, functions, class, methods, properties.

Camel case (eg: 'camelCase' ): Fields, locals and function parameters.

You are of course free to use your own convention, but for the sake of consistency it is recommended that this convention be used for the public interface of any modules you create intended for use by the Monkey community.

Types

Monkey is a statically typed language, which means that all variables, function parameters, function return values and expressions have an associated type that is known at compile time.

The following types are supported:

Boolean
Integer
Floating point
String
Array
Object

The Bool type

Values of type Bool are boolean values used to express the result of conditional expressions, such as the comparison operators, and to represent a true/false 'state' in general. A boolean value can only be either True or False.

The syntax used for declaring values and variables of boolean type is Bool. For example:

Local gamePaused:Bool = False

Boolean values are usually generated by the use of the comparison operators, for example:

If livesLeft<>0
doSomething()
End

However, in some circumstances Monkey will automatically convert a non-bool value to bool. This will occur when evaluating an expression for use with the If or While statements; the Until part of a Repeat loop; and when evaluating the arguments for the Not, Or and And operators. For example:

If livesLeft
doSomething()
End

See the conversions section in the expressions chapter for more information.

Also, notice that the Bool identifiers can also be declared by using the ? character. This two lines of source code are both valid and syntactically correct:

Local myVariable:Bool = True
Local myVariable? = True

The Int type

Values of type Int are signed integer values - that is, values with no fractional part. The range of integer values supported is target dependent, but is at least 32 bits. A 32 bit int can represent a range of values from: -2,147,483,648 to 2,147,483,647

The syntax used for declaring values and variables of integer type is Int. For example:

Local x:Int = 5

Integer literals are sequences of digits without a fractional part. Hexadecimal literals are also supported with the $ prefix. For example, the following are all valid integer literals:

0
1234
$3D0DEAD
$CAFEBABE

Also, notice that integer identifiers can also be declared by using the % character. This two lines of source code are both valid and syntactically correct:

Local myVariable:Int = 1024
Local myVariable% = 1024

The Float type

Values of type Float are signed numeric values with both an integer and fractional part. The range of floating point values support is target dependent, but is at least 32 bits.

The syntax used for declaring values and variables of floating point type is Float. For example:

Local gravity:Float = 9.81

Floating point literals are sequences of digits that include a fractional part, for example:

.0
0.0
.5
0.5
1.0
1.5
1.00001
3.14159265

Also, notice that floating point identifiers can also be declared by using the # character. This two lines of source code are both valid and syntactically correct:

Local myVariable:Float = 3.141516
Local myVariable# = 3.141516

The String type

Values of type String are used to represent sequences of characters, such as text. The size of each character in a string value is target dependent, but is at least 8 bits.

The syntax used for declaring values and variables of string type is String. For example:

Local name:String = "John Smith"

Strings are immutable meaning that once they are created they cannot be modified. Operations that 'modify' a string will always return a new string.

String literals are sequences of characters enclosed in "" (quotation marks). String literals may also include escape sequences - special sequences of characters used to represent unprintable characters.

You can use the following escape sequences in string literals:

Escape sequence	Character code
`~q`	34 (quotate mark ")
`~n`	10 (newline)
`~r`	13 (return)
`~t`	9 (tab)
`~z`	0 (null>
`~~`	126 (tilde ~)

Here are some examples of string literals:

"Hello World"
"~qHello World~q"
"~tIndented~n"

Strings can also be indexed and sliced.

The syntax for indexing a string is: StringExpression [ IndexExpression ]

Indexing a string returns the character code of the character at IndexExpression. Index 0 is the first character in the string.

IndexExpression must be greater than or equal to 0 and less than the length of StringExpression otherwise an error occurs.

Here are some examples of indexing a string:

Print "ABC"[0]              'prints 65 - the character code of 'A'
Print "ABC"[1]              'prints 66 - the character code of 'B'
Print "Hi~n"[2]             'prints 10 - the character code of '~n'

The syntax for slicing a string is: StringExpression[ StartExpression..EndExpression ]

Slicing a string returns a new string consisting of the characters within StringExpression starting at index StartExpression and ending at index EndExpression.

Both StartExpression and EndExpression are optional. If StartExpression is omitted, it defaults to 0. If EndExpression is omitted, it defaults to the length of the string.

StartExpression and EndExpression can also be negative, in which case they refer to offsets from the end of the string.

Here are some examples of slicing a string:

Print "Hello World"[4..7]   'prints "o W'
Print "Hello World"[..5]    'prints "Hello"
Print "Hello World"[5..]    'prints "World"
Print "Hello World"[..]     'prints "Hello World"

Strings also support a number of 'pseudo' methods and functions:

Method/Function	Description
Method Length() Property	Returns the number of characters in the string.
Method Compare( str:String )	Returns a value <0 if the current string is less than str, a value>0 if the current string is greater than str or 0 if this string is equal to str.
Method Find( subString:String )	Returns the index of the first occurance of subString within the current string.
Method Find( subString:String, startIndex )	Returns the index of the first occurance of subString within the current string, starting at index startIndex.
Method FindLast( subString:String )	Returns the index of the last occurance of subString within the current string.
Method FindLast( subString:String, startIndex )	Returns the index of the last occurance of subString within the current string, starting at index startIndex.
Method Contains( subString:String )	Returns true if the current string contains subString.
Method StartsWith( subString:String )	Returns true if the current string starts with subString.
Method EndsWith( subString:String )	Returns true if the current string ends with subString.
Method ToLower:String()	Returns the current string converted to lowercase.
Method ToUpper:String()	Returns the current string converted to uppercase.
Method Trim:String()	Returns the current string with all leading and trailing whitespace characters removed.
Method Split:String[]( separator:String )	Returns an array of strings that contains the substrings in the current string deliminated by separator.
Method ToChars:Int[]()	Converts string to an array of character codes.
Method Join:String( pieces:String[] )	Returns the elements of pieces concatened together with the current string inserted between each substring.
Function FromChar:String( char )	Returns a string of length 1 consisting of a single character code.
Function FromChars:String( chars:Int[] )	Creates a string from an array of character codes.

For example:

Print " Hello World ~n".Trim() 'prints "Hello World"
Print "Hello World".ToUpper() 'prints "HELLO WORLD"

Also, notice that string identifiers can also be declared by using the $ character. This two lines of source code are both valid and syntactically correct:

Local message:String = "Hello world"
Local message$ = "Hello world"

The Array type

An array is a linear sequence of values that can be addressed using an integer index.

Each array has an associated element type - that is, the type of the elements actually contained in the array. Due to the nature of Monkey, an array's element type is a purely static property. It is only known at compile time so arrays cannot be downcast at runtime.

The syntax used for declaring values and variables of array type is: ElementType []

For example:

Local box:Int[]            'an array of ints
Local ratio:Float[]        'an array of floats
Local thing:Int[][]        'an array of arrays of ints

An array literal is a (possibly empty) comma separated sequence of expressions enclosed with [ and ]. The expressions used in an array literal must be of the same type. For example:

Local box:Int[]=[]                              'an empty array literal
Local scores:Int[]=[10,20,30]                   'a comma separated sequence
Local text:String[]=["Hello","There","World"]   'a comma separated sequence

The syntax for indexing an array is: ArrayExpression [ IndexExpression ]. For example:

Local score:Int[]=[10,20,30] 'a comma separated sequence
Print score[1] 'prints "20"

Indexing an array yields a 'pseudo variable' of the array's element type that can be both read from and written to.

IndexExpression must be an integer expression greater than or equal to 0 and less than the length of the array otherwise an error occurs.

Like strings, arrays can also be sliced. The syntax for slicing an array is: ArrayExpression [ StartExpression .. EndExpression ].

Slicing an array returns 'sub array' of ArrayExpression starting at index StartExpression and ending at index EndExpression.

Both StartExpression and EndExpression are optional. If StartExpression is omitted, it defaults to 0. If EndExpression is omitted, it defaults to the length of the array.

StartExpression and EndExpression can also be negative, in which case they refer to offsets from the end of the array.

Here is an example of slicing an array:

Local text:String[]=["Cruel","Hello","World","There"] 'a comma separated sequence

Local helloWorld:=text[1..3] 'contains ["Hello","World"]

Arrays also support a number of pseudo methods:

Method	Description
Method Length() Property	The number of elements in the array.
Method Resize:Array( newLength )	Copies the first newLength elements of the current array into a new array of length newLength, and returns the new array.

For example:

Local text:String[]=["Hello","There","World"]        'a comma separated sequence

Print text.Length                'prints '3'

text=text.Resize( 2 )

Print text.Length                'prints '2'

The Object type

An object is an instance of a class, and contains a set of constants, variables, methods and functions.

The syntax used for declaring values and variables of object type is: ClassIdentifier

For example:

Local mine:MyClass = New MyClass

Please see the classes section for more information on declaring classes and creating objects.

Variables

A variable is a storage location used to hold values that change while your program runs.

All variables have an identifier, a type, and an optional initializer - an expression used to set the variable to an initial value.

The type of a variable can either be declared literally, or can be deduced from the variable's initializer.

Local variables

Local variables are temporary variables that disappear when the local scope they are declared in is destroyed.

Local variables may be declared within any local scope.

Each of the following creates a local scope:

The statements inside a function or method.

The statements inside an If, Else If or If block.

The statements inside a Case or Default block.

The statements inside a While, Repeat or For loop.

The syntax for declaring a local variable is:

Local Identifier : Type [ = Expression ]

Or...

Local Identifier := Expression

For example:

Local age:Int=10
Local age:=10

Global variables

Global variables are variables that persist during the execution of your program.

Global variables may be declared at module scope, or within a class declaration.

The syntax for declaring a global variable is:

Global Identifier : Type [ = Expression ]

Or...

Global Identifier := Expression

For example:

Global isPlayerAlive:Bool = True

Field variables

Field variables are variables that persist as long as the object they belong to.

Field variables can only be declared within a class declaration.

The syntax for declaring a field variable is:

Field Identifier : Type [ = Expression ]

Or...

Field Identifier := Expression

Constants

A constant is a value that is evaluated at compile time, and that does not change throughout the execution of a program.

Constants may be declared at module scope, within class scope or within any local scope.

The syntax for declaring a constant is:

Const Identifier : Type = Expression

Or...

Const Identifier := Expression

Expressions

Expressions are the parts of a program that perform calculations, make logical comparisons and return values from methods or functions.

Operators

Operator Syntax	Description
`New` ClassType	Create a new Object
`Null`	The null object
`True`	Boolean true
`False`	Boolean false
`Self`	Self
`Super`	Super
Literal	Literal
Identifier	Identifier

`.` Identifier	Scope member access
`(` ExpressionSeq `)`	Invoke
`[` Expression `]`	Index

`+`	Unary plus
`-`	Unary minus
`~`	Bitwise complement
`Not`	Boolean inverse

`*`	Multiplication
`/`	Division
`Mod`	Modulus
`Shl`	Bitwise shift left
`Shr`	Bitwise shift left (signed)

`+`	Addition
`-`	Subtraction

`&`	Bitwise 'and'
`~`	Bitwise 'xor'

`\|`	Bitwise 'or'

`=`	Equals
`<`	Less than
`>`	Greater than
`<=`	Less than or equals
`>=`	Greater than or equals
`<>`	Not equals

`And`	Condititonal 'and'

`Or`	Conditional 'or'

Operators are grouped by priority.

Balancing argument types

When performing binary arithmetic (*, /, Mod, +, -) or comparison operations (=, <, >, <=, >=, <>), operator arguments are 'balanced' according to the following rules:

If either operand is not string, float or int, then error,

else if either operand is a string, then the balanced type is string,

else if either operand is a float, then the balanced type is float,

else the balanced type is int.

In the case of arithmetic operations, arguments are first implicitly converted to the balanced type if necessary, and the result is also of the balanced type.

In the case of comparison operations, arguments are first implicitly converted to the balanced type if necessary, and the result is boolean.

The only valid arithmetic operation that can be performed on strings is addition, which performs string concatentation on the arguments.

Conditional operators

The arguments of conditional operations (And, Or) are first converted to boolean if necessary and the result is boolean.

In the case of Or, if the left-hand-side expression evaluates to true, the right-hand-side expression is not evaluated.

For example:

If car<>Null Or GetSpeed()>10 Then...

In the above example, if car is not Null, then the right-hand-side of the Or is not evaluated - ie: the GetSpeed function is never called.

In the case of And, if the left-hand-side expression evaluates to false, the right-hand-side expression is not evaluated.

For example:

If enemies.Count > 0 And HasEnemyInSight() Then ...

In the above example, if enemies.Count is <= 0, then the right-hand-side of the And is not evaluated - ie: the hasEnemyInSight function is never called.

Bitwise operators

When performing bitwise (Shl Shr & | ~) operations, arguments are first implicitly converted to integers if necessary before the operation is performed. The result is also an integer.

Implicit conversions

Implicit conversions are automatic conversions performed when assigning a value to a variable, passing parameters to a function, returning a value from a function or when balancing operator operands.

Monkey supports the following implicit conversions:

Source type	Target type	Notes
Boolean	Integer	Return 1 if boolean value is true, 0 if false.
Integer	Floating point
Integer	String
Floating point	Integer	Value is converted by discarding fractional part.
Floating point	String	Conversion is target dependent.
Derived class object	Base class object	Upcast operation.

Explicit conversions

Explicit conversions are conversions from one type to another type which can be performed manually by the programmer .

The syntax for performing an explicit conversion is: TargetType ( Expression )

For example:

Local energyFloat:Float = 120.1000002001

Local energyInt:Int = Int(energyFloat) 'Is 120 now

You can perform the following explicit conversions in Monkey:

Source type	Target type	Notes
Integer	Boolean	Result is true if source<>0, else false.
Floating point	Boolean	Result is true if source<>0.0, else false.
Array	Boolean	Result is true if source.Length<>0, else false.
Object	Boolean	Result is true if source<>Null, else false.
String	Boolean	Result is true if source<>"", else false.
String	Integer	Conversion is target dependant.
String	Floating point	Conversion is target dependant.
Base class object	Derived class object	Result is null if source is not a superclass of derived class.

In some circumstances, Monkey will automatically perform an explicit conversion of a non-bool value to bool for you. This will occur when evaluating an expression for use with the If and While statements; the Until part of a Repeat loop; and when evaluating the arguments for the Not, Or and And operators. This allows you to use 'shortcut' code such as: If x Then y without the need to compare x with 0, "", [] or null.

Boxing and unboxing conversions

A 'box' object is an object designed to contain a single primitive int, float or string value. The process of placing a value into a box object is known as 'boxing', while extracting a value from an object is known as 'unboxing'. To help with writing box objects, Monkey provides some simple features for boxing and unboxing values:

An int, float or string value will be automatically converted to a new box object if that object provides a suitable New( Int ), New( Float ) or New( String ) constructor.

An object will be automatically converted to an int, float or string value if that object provides a suitable To:Int(), ToFloat:Float() or ToString:String() method.

For example, here is a simple box class designed to hold an integer value:

Class IntBox
    Field value:Int

    Method New( value:Int )
        Self.value=value
    End

    Method ToInt:Int()
        Return value
    End
End

Function Main()
    Local box:IntBox
    box=10

    Local t:Int=box
    Print t
End

Statements

Program statements may only appear within method or function declarations.

A ; character may optionally appear after any statement, and multiple statements may be placed on the same source code line if separated by the ; character.

If statement

The If statement allows you to conditionally execute a block of statements depending on the result of a series of boolean expressions.

The first boolean expression that evaluates to true will cause the associated block of statements to be executed. No further boolean expressions will be evaluated.

If no boolean expression evaluates to true, then the final else block will be executed if present.

The syntax for the If statement is:

If Expression [ Then ]
     Statements...
ElseIf Expression [ Then ]
     Statements...
Else
     Statements...
EndIf

There may be any number of ElseIf blocks, or none. The final Else block is optional.

End or End If may be used instead of EndIf, and Else If may be used instead of ElseIf.

In addtion, a simple one line version of If is also supported:

If Expression [ Then ] Statement [ Else statement ]

The Select statement

The Select statement allows you to execute a block of statements depending on a series of comparisons.

The first comparison to produce a match will cause the associated block of statements to be executed.

If no comparisons produce a match, then the final default block will be executed if present.

The syntax for the Select statement is:

Select Expression
Case Expression [ , Expression... ]
Statements...
Default
Statements...
End [ Select ]

There may be any number of Case blocks, or none. The final Default block is optional. If the default block is present, it must appear after all Case blocks.

While loop

The While loop allows you to execute a block of statements repeatedly while a boolean expression evaluates to true.

Note that a While loop may never actually execute any of it's statements if the expression evaluates to false when the loop is entered.

The syntax for the While loop is:

While Expression
Statements...
Wend

End or End While may be used instead of Wend.

Exit and Continue may be used within a While loop to abruptly terminate or continue loop execution.

Repeat loop

Like the While loop, the Repeat loop also allows you to execute a block of statement repeatedly while a boolean expression evaluates to true.

However, unlike a While loop, a Repeat loop is guaranteed to execute at least once, as the boolean expression is not evaluated until the end of the loop.

The syntax for Repeat/Until loops is:

Repeat
Statements...
Until Expression

Or...

Repeat
Statements...
Forever

Exit and Continue may be used within a While loop to abruptly terminate or continue loop execution.

Numeric For loop

A numeric For loop will continue executing until the value of a numeric index variable reaches an exit value.

The index variable is automatically updated every loop iteration by adding a constant step value.

The syntax for a numeric For loop is:

For [ Local ] IndexVariable = FirstValue To | Until LastValue [ Step StepValue ]
Statements...
Next

End or End For may be used instead of Next.

If present, Local will create a new local index variable that only exists for the duration of the loop. In addition, IndexVariable must include the variable type, or := must be used instead of = to implicitly set the variable's type.

If Local is not present, IndexVariable must be a valid, existing variable.

The use of To or Until determines whether LastValue should be inclusive or exclusive.

If To is used, the loop will exit once the index variable is greater than LastValue (or less than if StepValue is negative).

If Until is used, the loop will exit once the index variable is greater than or equal to LastValue (or less than or equal to if StepValue is negative).

If omitted, StepValue defaults to 1.

Exit and Continue may be used within a numeric For loop to abruptly terminate or continue loop execution.

For EachIn loop

A For EachIn loop allows you to iterate through the elements of a collection.

A collection is either an array, a string, or a specially designed object.

The syntax for a For EachIn loop is:

For [ Local ] IndexVariable = EachIn Collection
Statements...
Next

End or End For may be used instead of Next.

If present, Local will create a new local index variable that only exists for the duration of the loop. In addition, IndexVariable must include the variable type, or := must be used instead of = to implicitly set the variable's type.

If Local is not present, IndexVariable must be a valid, existing variable.

If Collection is an array, the loop will iterate through each element of the array, and the type of the index variable must match the element type of the array.

If Collection is a string, the loop will iterate through each each character code of the string, and the type of the index variable must be numeric.

If Collection is an object, it must provide the following method:

Method ObjectEnumerator:Object()

The object returned by this method must itself provide the following methods:

Method HasNext:Bool()
Method NextObject:Object()

This allows you to build 'collection' style objects, such as the List and Map classes included in the standard Monkey modules that can be iterated through using For EachIn loops.

Exit and Continue

Exit can be used within While, Repeat and For loops to abruptly exit the loop before the loop termination condition has been met.

Continue can be used within While, Repeat and For loops to force the loop to abruptly skip to the next loop iteration, skipping over any statements that may be remaining in the current loop iteration.

Assignment statements

An assignment statement modifies a variable's value, and has the syntax:

VarExpression Operator Expression

Where VarExpression is an expression that evaluates to a variable, and Operator is one of the following:

=
**=*
/=
Shl=
Shr=
Mod=
+=
-=
&=
~=
|=

The = operator is used for plain assignment, while the remaining operators are used for update assignments.

Expression statements

You may also use certain expressions as program statements. These are:

Function or method call expressions.

New expressions.

Functions

A function is a self contained block of statements that can be called (or invoked) repeatedly from elsewhere in the program. Functions can also be passed parameters and return a result.

The syntax for declaring a function is:

Function Identifier : ReturnType ( Parameters )
Statements...
End [ Function ]

For example:

Function Eat:Void( amount:Int )
...
End

Parameters is a comma separated sequence of function parameters:

Identifier : Type [ = InitExpression ]

Or...

Identifier := InitExpression

If you provide an InitExpression when declaring a function parameter, this means that the parameter has a default value and that the parameter can be optionally omitted when the function is called.

Once you have declared a function, it can be called with the syntax:

FunctionIdentifier ( Arguments )

where Arguments is a comma separated sequence of expressions.

For example:

Function Sum:Int( x:Int,y:Int )
Return x+y
End

Function Main()
Print Sum( 10,20 )
End

Here is an example of using default parameters:

Function Sum( x:Int=0,y:Int=0,z:Int=0 )
    Print x+y+z
End

Function Main()
    Print Sum()         'same as calling Sum( 0,0,0 )
    Print Sum( 10,20 )  'same as calling Sum( 10,20,0 )
    Print Sum( 10,,30 ) 'same as calling Sum( 10,0,30 )
End

Function overloading

Functions can also be overloaded. This means that multiple declarations can share the same name, as long as they each have different parameters. Methods can be overloaded in exactly the same way as functions.

When a function is called, Monkey looks at the number and type of the parameters used in the call and looks for a matching overloaded version to use. For example:

Function Add( value:Int )
End

Function Add( value:Float )
End

Function Add( value:String )
End

Function Main()
    Add( 10 )   'calls first version as 10 is of type Int
    Add( 10.0 ) 'calls second version as 10.0 is of type Float
    Add( "10" ) 'calls third version as "10" is of type String
End

The number of parameters can also be used to differentiate between overloaded functions. For example:

Function Set( x )
End

Function Set( x, y )
End

Function Main()
Set( 10 ) 'calls first version
Set( 10,20 ) 'calls second version as it has two parameters
End

When determining which overloaded version to actually use, Monkey uses the following logic:

If an overloaded version is found that is an exact match for the number and type of function call parameters, that version is used. Note that if the function call involves the use of any default parameters, it is not considered an exact match.

Otherwise, if there is exactly one overloaded version that can be called by implicitly converting the function call parameters, that version is used.

Otherwise, an error is generated. In this case, you will need to manually cast some or all of the function call parameters to create an exact match.

For example:

Function Add( value:Int )
End

Function Add( value:String )
End

Function Main()
    Add( 10 )   'OK, calls first version
    Add( "10" ) 'OK, calls second version
    Add( 10.0 ) 'error - unable to determine which version to call
End

The error is caused by the fact that the function call parameter - '10.0' - is a floating point value and can therefore be implicitly converted to either an integer or a string, so Monkey cannot decide which overload to use.

To solve this problem, you would need to explicitly cast the parameter to either an integer or a string to give Monkey a 'hint' about which version you want used. For example:

Add( Int(10.0) ) 'Casts the float to an integer, calls first version

Methods

A Method is a function that is bound to a class. A method has implicit access to all members of its class, such as fields, globals and other methods and functions..

The syntax for declaring a method is similar to that for declaring a function:

Method Identifier : ReturnType ( Parameters ) [ Property ]
Statements...
End [ Method ]

Within a method you can also use the special Self and Super variables:

Self may be used within a method to access the object the method is associated with.

Super may be used within a method to call 'super class' methods.

The optional Property keyword can be used to declare a 'property method'.

A property method with 0 parameters can be invoked without any brackets. A property method with 1 parameter can be invoked be using it as the left-hand-side of an assignment statement, in which case the right-hand-side expression of the assignment is passed to the property method.

You can therefore create methods that behave like fields, but actually execute code when they are read or written. You can use method overloading to provide both read and write property methods, or provide just a read method, or even just a write method.

It is illegal to declare a property method with 2 or more parameters.

Classes

A class is a kind of 'blueprint' for creating objects at runtime.

The syntax for declaring a class is:

Class Identifier [ < Parameters > ] [ Extends Class ] [ Implements Interfaces ]
Declarations...
End [ Class ]

Classes can contain field, method, constant, global and function declarations.

If no base class is specified using Extends, the class defaults to extending the built in Object class.

The Implements keyword is used to implement interfaces, and must be followed by a comma separated list of interface names. Please refer to the Interfaces section for more on interfaces.

A class is also a valid scope, and any constants, globals and functions declared within a class can be accessed outside of the class using the scope member access operator '.'. For example:

Class C
Global T
End

Function Main()
C.T=10
End

Once you have declared a class, you can create objects of that class at runtime using the New operator. For example:

Class MyClass
    Field x,y,z
End

Function Main()
    Local myObject:=New MyClass
    myObject.x=10
    myObject.y=20
    myObject.z=30
End

Constructors

Constructors are special methods that are called each time an object is created with New.

To declare a constructor, you simply declare a class method and name it New.

Constructors can take parameters and can be overloaded.

To invoke a super class constructor within a constructor, use the special Super variable.

Generic classes

Generic classes allow you to write code that is not specific to a single data type.

A generic class is declared in a similar way to a normal class, only with an additional set of 'type parameters' enclosed within < and >.

For example:

Class Pointer<T>
    Method Set( data:T )
        _data=data
    End

    Method Get:T()
        Return _data
    End

    Private

    Field _data:T

End

Type parameters can be any valid identifier. Here, T is such a type parameter.

Within the declaration of a generic class, type parameters may be used anywhere a type is normally expected, for example, when declaring variables and function return types, and when creating new objects or arrays.

When it comes to actually using a generic class, you must provide actual types to be used in place of type parameters. Types parameters can be of any valid type, including int, float, string and array.

For example:

Class Actor
End

Function Main()
    Local pointer:Pointer<Actor>
    pointer=New Pointer<Actor>
    pointer.Set New Actor
    Local actor:=pointer.Get()
End

The syntax Pointer<Actor> indicates an 'instantiation' of the generic class Pointer<T>.

This is in itself a unique class, so each time you use the Pointer<T> class with a different type for T, you are actually creating a whole new class.

Generic classes are commonly used for writing container classes such as lists, stacks and so on, and the standard Monkey modules provide a set of simple generic container classes.

Interfaces

An interface is similar to a class, except that it can only contain constants and abstract methods.

Classes can implement an interface using the Implements keyword in the class declaration.

Classes that implement an interface must declare each method declared in the interface.

An interface can be used where ever a class is expected, for example when declaring the types of variables, or function return types. An interface cannot however be used with New.

An Interface can also optionally extend existing interfaces, in which cases all methods in all extended interfaces must be declared by any implementing classes.

Interfaces can not be generic.

The syntax for declaring an interface is:

Interface Identifier [ Extends Interfaces ]
Declarations...
End [ Interface ]

All methods declared inside an interface are automatically treated as abstract, and can therefore have no 'body'.

Here is an example of using interfaces:

Interface Moveable
    Method Move()
End

Interface Drawable
    Method Draw()
End

Class Actor Implements Moveable,Drawable
    Method Move()
        Print "Actor.Move()"
    End
    Method Draw()
        Print "Actor.Draw()"
    End
End

Function Move( moveable:Moveable )
    moveable.Move
End

Function Draw( drawable:Drawable )
    drawable.Draw
End

Function Main()
    Local actor:=New Actor

    Move actor
    Draw actor
End

Exceptions

Exceptions are special objects that can be 'thrown' to inform your program of unusual or abnormal behavior.

By placing code inside a 'try' block, you can catch thrown exceptions with a corresponding 'catch' block. For example...

Function Main()
    Try
        Print "Hello World!"
        Throw New Throwable
        Print "Where am I?"
    Catch ex:Throwable
        Print "Caught a Throwable!"
    End
End

Try this with and without the throw statement.

Throw statements may appear anywhere in your application, not just inside a try block. When an object is thrown, it is thrown to the most recently executed try block capable of catching the object.

The class of objects used with throw and catch must extend the special built-in class Throwable. The Throwable class itself simply extends Object and provides no new methods or fields, so you may wish to extend Throwable to create your own exception classes with more functionality.

You can also catch multiple classes of exception object per try block, for example:

Class Ex1 Extends Throwable
End

Class Ex2 Extends Throwable
End

Function Main()
    For Local i:=1 To 10
        Try
            If (i & 1) Throw New Ex1 Else Throw New Ex2
        Catch ex:Ex1
            Print "Caught an ex1!"
        Catch ex:Ex2
            Print "Caught an ex2!"
        End
    Next
End

When a try block has multiple catch blocks and an exception is thrown, the first catch block capable of handling the exception is executed. If no suitable catch block can be found, the exception is passed to the next most recently executed try block, and so on.

If no catch block can be found to catch an exception, a runtime error occurs and the application is terminated.

Modules

A Monkey module corresponds to a single Monkey source file, and provides a named scope for the constants, globals, functions and classes declared in that file. Every Monkey source file declares a module, and every module has an associated source file.

The name of the module scope is the same as the name of the file (minus the directory path and file extension), so the names of Monkey source files must also be valid Monkey identifiers.

It is also strongly recommend that file/module names be completely lowercase - both to prevent any issues with cased/uncased filesystems and to provide consistency with the standard module set.

One module may import another using the import statement. All import statements must appear at the top of a module before any declarations. The syntax for an import statement is:

Import ModulePath

Where ModulePath describes the file location of the Monkey module to import. This must be a sequence of 'dot' separated identifiers, and is treated as a relative filesystem path with dots representing directory separators. The last component in the path represents either an actual .monkey source file, or a directory containing a .monkey source file of the same name.

Given a module's relative path, Monkey will look for an actual module to import in the following locations (and in this order):

The current directory - ie: the directory the importing file is in.

The project directory - ie: the directory the main source file is in. This is the source file that was passed to the 'trans' compiler, and that contains the declaration for Main().

The modules directory - ie: the directory named 'modules' in the Monkey distribution.

For example, given the following import directive:

Import myutil.mycolor

Monkey will first look for the files myutil/mycolor.monkey and myutil/mycolor/mycolor.monkey in the current directory.

(Note: the reason modules are allowed to be represented as either a single .monkey file, or as a .monkey file within a directory of the same name is for pure convenience. Sometimes it's more convenient for a module to consist of a single file, while sometimes it's more convenient for a module to have its own directory.)

If either is found, it is imported into the current module and the search ends.

If both are found, an error is generated.

If neither is found the search continues with the project directory and, failing that, the modules directory.

If the module is not found anywhere, an error is generated.

Once successfully imported, the importing module can access the declarations made in the imported module, by using the imported module's name as a scope.

Here is a simple import example:

'----- file1.monkey -----
Import file2                'after this, file2 can be used as a scope

Function Main()
    Print file2.X        'access global X in file2 module

    file2.Test                'access function Test in file2 module
End

'---- file2.monkey ----
Global X:=1

Function Test()
    Print "file2.Test"
End

When accessing identifiers in imported modules, Monkey allows you to omit the module scope as long as there are no 'clashes' between identifiers in multiple modules. For example:

'----- file1.monkey ----
Import file2
Import file3

Function Main()

    Print X     'OK, accesses file2.X
    Print Y     'OK, accesses file3.Y
    Test        'ERROR! Which Test? file2.Test or file3.Test?
    file2.Test  'OK, I now know which module to get Test from

End

'----- file2.monkey -----
Global X:=1

Function Test()
    Print "file2.Test"
End

'----- file3.monkey -----
Global Y:=2

Function Test()
    Print "file3.Test"
End

By default, any imports made by a module are automatically made available to importers of that module. That is, if module X imports module Y, and module Y imports module Z, the result is that module X effectively imports module Z.

However, if an import is declared to be private, that import is NOT made available. For example:

'----- file1.monkey -----
Import file2
Function Main()

    Print X  'OK, accesses file2.X
    Print Y  'OK, accesses file3.Y
    Print Z  'ERROR! can't see file.Z

End

'----- file2.monkey -----
Import file3                'Public import: When you import file2, you also import file3

Private
Import file4                'Private - ie: internal use only. Only file2 can access file4. file1 cannot access file4.

Public
Global X:=1

'----- file3.monkey -----
Global Y:=2

'----- file4.monkey -----
Global Z:=3

Modules can be stored in a directory hierarchy and imported using a 'dotted' module path, for example:

'----- file1.monkey -----
Import file2
Import util.file3

Function Main()
Print file2.X
Print file3.Y
End

'----- util/file2.monkey ----
Global X:=1

'----- util/file3.monkey -----
Global Y:=2

Note that the directory path (in this case, 'util') is not used in any way except to locate the module. The module name is still just 'file3' - not 'util.file3'.

The Alias directive

The Alias directive allows you to assign a local name to a constant, global, function or class declared in another module. This can be used to create 'shortcuts' for clashing identifiers.

The syntax for Alias is:

Alias Identifier = ModulePath . Identifier

Alias directives must appear in the 'import' section of a module, before any code.

For example:

'----- file1.monkey -----
Import file2
Import file3

Alias T=file2.T 'which 'T' to use

Function Main()
Print T 'Prints '1'
End

'----- file2.monkey -----
Global T:=1

'----- file3.monkey -----
Global T:=2

Public and Private

The Public and Private directives are used to control the visibility of subsequent declarations in a module or class.

If the Public directive is used in the main body of a module, all subsequent declarations will be public, and will be visible outside of the current module.

If the Private directive is used in the main body of a module, all subsequent declarations will be private and will not be visible outside of the current module.

For example:

Private
Global x,y,z 'These are private to the current module

Public
Global P,Q,R 'These can be used by any module

When used inside a class declaration, Public and Private work in a similar way to control the visibility of subsequent member declarations. For example:

Class MyClass
    Private
    Field x,y,z        'these are NOT visible outside of this module.

    Public
    Field P,Q,R        'these ARE visible outside of this module.
End

Note that private class members are not private to the class, but to the entire module. This means that code outside of the class but within the same module can still access class private members.

External declarations

The Extern directive is used to connect Monkey code to non-Monkey code. It lets you mix Monkey code (to be translated into the target platform language) with native target platform code.

When the Extern directive is used in the main body of a module, all subsequent global, function and class declarations will be treated as external declarations.

External declarations are assumed to be implemented elsewhere in native code, and as such may not contain a 'body'.

In the case of external global variables, this means the global may not be initialized - it is assumed to be initialized by native code.

In the case of external functions, this means the function may not contain any code, and must not be terminated with an End directive.

In the case of external classes, this means any globals or methods declared in the class may not contain a 'body' either.

External declarations may however be assigned a 'symbol' in the form of a string literal. This is the native symbol to be used by the Monkey translator when the declaration is referenced by Monkey code.

By default, external declarations are public. You can use Extern Private to prevent external declarations from being visible outside the current module.

Here are some examples of using extern:

Extern

Global ActiveDriver:Driver="xyzActiveDriver"  'Native name of this global is xyzActiveDriver

Class Driver="xyzDriver"   'The native name of this class is 'xyzDriver'.
    Method Method1()       'By default, native name is same as declaration name - Method1 here.
    Method Method2()       'native name is Method2
End

Public        'return to public declarations

Memory Management

Monkey is a garbage collected language, and depends on the underlying target language to provide memory management.

Finalizers are not supported. If you need an object to be 'destroyable', you will need to add a 'Destroy' type method.

The garbage collector is capable of collecting cyclic data structures such as linked lists automatically.

The current C++ garbage collector will only collect garbage when control is returned to the OS. In the case of C++ Mojo targets such as IOS and GLFW, this occurs after any of the 'On' methods such as OnCreate, OnUpdate etc return.

In general, the best way to use the garbage collector is to ignore it! Although such practices as 'nulling out' object references are common, they are seldom required.

But it's a good idea to monitor your apps memory requirements as you develop anyway. This will allow you to catch any memory issues, GC related or otherwise, early on.

The preprocessor

Monkey contains a very simple built-in preprocessor based on the syntax of the Monkey If statement that allows you to enable or disable blocks of code from being generated or translated, based on certain conditions.

The following preprocessor directives are supported:

#If
#ElseIf
#Else
#End
#Rem
#Print
#Error

Preprocessor directives must appear at the start of a line, and may be preceded by optional whitespace.

The #If and #Else If directives must be followed by a constant Monkey expression. If this expression evaluates to true, then code generation is enabled, otherwise it is disabled.

The following built in constants may be used in preprocessor expressions:

Constant	Description
HOST	Host operatintg system, one of: winnt macos linux
LANG	Target language, one of: js as cs cpp java
TARGET	Target system, one of: ios android winrt glfw html5 flash xna psm
CONFIG	Target build config, one of: debug release
CD	Directory of source file being built
MODPATH	Module being built

The #Rem directive is exactly the same as #If False - it unconditionally disables code generation. Note that this allows 'block rems' to be 'nested'.

Monkey language reference

Contents

Language keywords and reserved identifiers

Monkey naming conventions

The Bool type

The Int type

The Float type

The String type

The Array type

The Object type

Local variables

Global variables

Field variables

Operators

Balancing argument types

Conditional operators

Bitwise operators

Implicit conversions

Explicit conversions

Boxing and unboxing conversions

If statement

The Select statement

While loop

Repeat loop

Numeric For loop

For EachIn loop

Exit and Continue

Assignment statements

Expression statements

Functions

Function overloading

Constructors

The Alias directive